App Manifest - Homey Apps SDK v2 Documentation

App Manifest

It's strongly suggested to use the compose plugin to create your App's manifest. Read more about compose here: Homey Compose

File structure

The file structure of your app looks as follows.

com.athom.example
├── README.txt
├── api.js
├── app.js
├── app.json
├── assets
│   ├── icon.svg
│   └── images
│       ├── large.png
│       └── small.png
├── drivers
│   └── my_driver
│       ├── assets
│       │   ├── icon.svg
│       │   └── images
│       │       ├── large.png
│       │       └── small.png
│       ├── device.js
│       └── driver.js
├── env.json
├── locales
│   ├── en.json
│   └── nl.json
└── settings
    └── index.html

Click a file in the tree to learn more about it.

Manifest file

The App Manifest, a JSON file called /app.json, contains all metadata for your app. It specifies Flow Cards, Drivers, etc.

Example

Most documentation specify their own properties for the /app.json file. An example file is shown below.

/app.json

{
  "id": "my.company.example",
  "version": "1.0.0",
  "compatibility": ">=2.4.0",
  "sdk": 2,
  "brandColor": "#FF0000",
  "name": {
    "en": "My App",
    "nl": "Mijn App"
  },
  "description": {
    "en": "Adds support for certain devices.",
    "nl": "Voegt ondersteuning toe voor bepaalde apparaten."
  },
  "category": "appliances",
  "tags": {
    "en": [ "example" ],
    "nl": [ "voorbeeld" ]
  },
  "images": {
    "large": "/assets/images/large.png",
    "small": "/assets/images/small.png"
  },
  "permissions": [
    "homey:manager:speech-output",
    "homey:manager:ledring"
  ],
  "author": {
    "email": "john@doe.com",
    "name": "John Doe"
  },
  "contributors": {
    "developers": [
      {
        "name": "Alice the Wild",
        "email": "alicewild@gmail.com"
      }
    ],
    "translators": [
      {
        "name": "Klemens Kohlmann"
      }
    ]
  },
  "contributing": {
    "donate": {
      "paypal": {
        "username": "my_paypal.me_username"
      }
    }
  },
  "bugs": {
    "url": "https://bitbucket.org/athom/com.athom.myapp/issues"
  },
  "homeyCommunityTopicId": 1234,
  "source": "https://github.com/athombv/com.athom.myapp",
  "homepage": "https://homey.app",
  "support": "mailto:support@homey.app",
  "signals": {
    // ...
  },
  "flow": {
    "actions": [
      {
        "id": "my_action",
        "title": {
          "en": "My Action",
          "nl": "Mijn Actie"
        }
      }
    ]
  },
  "drivers": [
    {
      "id": "my_driver",
      "class": "socket",
      "capabilities": [ "onoff", "dim" ],
      "name": {
        "en": "My Driver",
        "nl": "Mijn Driver"
      },
      "images": {
        "large": "/drivers/my_driver/assets/images/large.png",
        "small": "/drivers/my_driver/assets/images/small.png"
      },
      "gtin": [ "123456789111" ],
    }
  ],
  "capabilities": {
    // ...
  },
  "screensavers": [
    {
      "name": "my_screensaver",
      "title": {
        "en": "My Screensaver"
      }
    }
  ]
}

Properties

`id`

The ID of your app. This is a reversed domain-name.

`version`

A Semantic Version of your app. Note that pre-release versions (e.g. 1.0.0-rc.1) are not allowed.

`compatibility`

A Semantic Version indicating a range of Homey versions your app is compatible with.

Use at least "compatibility": ">=1.5.0" (larger or equal than v1.5.0).

`sdk`

The SDK level of your app. Should be 2.

`brandColor`

A HEX string for the app's brand color. Colors that are too bright will not be validated. If no brandColor is provided, an unique app color will be automatically generated.

`name`

An i18n-object with the name of your app.

`description`

An i18n-object with the description (oneliner) of your app.

`category`

A string with the Homey App Store category.

Allowed categories are: lights, video, music, appliances, security, climate, tools, internet, localization, energy.

`tags`

An i18n-object with searchable tags for the App Store.

`images`

An object containing two paths, small and large.

`permissions`

An array of Permissions.

`author`

An object indicating the author of the app. The field author.name is required, author.email is optional.

`contributors`

An object with developers, following the same format as author.

`contributing`

An object to show people how to contribute to app development. Only donate.paypal is supported for now, which will show a PayPal button in the sidebar.

`bugs`

An object with a property url to link to. This is rarely necessary, only when using a non-common Git system.

`homeyCommunityTopicId`

A number with the discussion ID of the Homey Community. When provided, this shows a link on the App Store. Get the discussion ID from the topic's URL.

`source`

A string, starting with https://, to link to your app's source code.

`homepage`

A string, starting with https://, to link to your app's homepage.

`support`

A string, starting with https:// or mailto:, to link to your app's support website or e-mail address.

`signals`

See Signals.

`flow`

See Flow.